perf: improve field indexing in JSON StructArrayDecoder (1.7x speed up) #9086

Weijun-H · 2026-01-02T13:31:04Z

Which issue does this PR close?

Closes #NNN.

Rationale for this change

Optimize JSON struct decoding on wide objects by reducing per-row allocations and repeated field lookups.

What changes are included in this PR?

Reuse a flat child-position buffer in StructArrayDecoder and add an optional field-name index for object mode.
Skip building the field-name index for list mode; add overflow/allocation checks.

decode_wide_object_i64_json
                        time:   [11.828 ms 11.865 ms 11.905 ms]
                        change: [−67.828% −67.378% −67.008%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 3 outliers among 100 measurements (3.00%)
  2 (2.00%) high mild
  1 (1.00%) high severe

decode_wide_object_i64_serialize
                        time:   [7.6923 ms 7.7402 ms 7.7906 ms]
                        change: [−75.652% −75.483% −75.331%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 1 outliers among 100 measurements (1.00%)
  1 (1.00%) high mild

Are these changes tested?

Yes

Are there any user-facing changes?

No

scovich

Not sure I understand the indexing code well enough to say whether that part is correct, but the idea of using an optional index for field name lookups makes a lot of sense to me.

scovich · 2026-01-05T21:33:03Z

arrow-json/src/reader/struct_array.rs

    }
 }
+
+fn build_field_index(fields: &Fields) -> Option<HashMap<String, usize>> {


qq: Do lifetimes coincide so that we could return Option<HashMap<&str, usize>> instead?

Yes, the lifetimes do coincide. we can use HashMap<&'a str, usize> by taking fields: &'a Fields as a parameter, which avoids the self-referential struct problem. However, this would require threading the lifetime parameter <'a> through the entire decoder system across many files. Since the lookup performance is identical, I don’t think it’s worth the added complexity.

maybe it would be a good follow on PR

alamb

Thanks @Weijun-H and @scovich

alamb · 2026-01-06T22:30:41Z

arrow-json/benches/reader.rs

+use std::fmt::Write;
+use std::sync::Arc;
+
+fn build_schema(field_count: usize) -> Arc<Schema> {


can you please add some comments here with an example of what this code does / what patterns of input it creates?

Also, it would help me to reproduce your results if you could make a separate PR with the benchmarks (so I can compare main to the PR)

separate benchmark here

#9107

alamb · 2026-01-06T22:31:31Z

arrow-json/src/reader/struct_array.rs

    }
 }
+
+fn build_field_index(fields: &Fields) -> Option<HashMap<String, usize>> {


maybe it would be a good follow on PR

alamb · 2026-01-10T12:38:20Z

run benchmark json-reader

alamb-ghbot · 2026-01-10T12:38:44Z

🤖 Hi @alamb, thanks for the request (#9086 (comment)).

scrape_comments.py only supports whitelisted benchmarks.

Standard: (none)
Criterion: array_iter, arrow_reader, arrow_reader_clickbench, arrow_reader_row_filter, arrow_statistics, arrow_writer, bitwise_kernel, boolean_kernels, buffer_bit_ops, cast_kernels, coalesce_kernels, comparison_kernels, concatenate_kernel, csv_writer, encoding, filter_kernels, interleave_kernels, json-reader, metadata, row_format, take_kernels, union_array, variant_builder, variant_kernels, variant_validation, view_types, zip_kernels

Please choose one or more of these with run benchmark <name> or run benchmark <name1> <name2>...

Weijun-H · 2026-01-10T12:55:49Z

run benchmark json-reader

alamb-ghbot · 2026-01-10T12:55:52Z

🤖 Hi @Weijun-H, thanks for the request (#9086 (comment)). scrape_comments.py only responds to whitelisted users. Allowed users: Dandandan, Omega359, adriangb, alamb, comphead, geoffreyclaude, klion26, rluvaton, xudong963, zhuqi-lucas.

alamb-ghbot · 2026-01-10T17:30:18Z

🤖 ./gh_compare_arrow.sh gh_compare_arrow.sh Running
Linux aal-dev 6.14.0-1018-gcp #19~24.04.1-Ubuntu SMP Wed Sep 24 23:23:09 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux
Comparing optimize-json-scan (06ded8b) to b2aeab1 diff
BENCH_NAME=json-reader
BENCH_COMMAND=cargo bench --features=arrow,async,test_common,experimental --bench json-reader
BENCH_FILTER=
BENCH_BRANCH_NAME=optimize-json-scan
Results will be posted here when complete

alamb-ghbot · 2026-01-10T17:46:26Z

🤖: Benchmark completed

Details

group                                        main                                   optimize-json-scan
-----                                        ----                                   ------------------
decode_binary_hex_json                       1.05     93.1±0.89ms        ? ?/sec    1.00     88.5±1.03ms        ? ?/sec
decode_binary_view_hex_json                  1.05     94.2±0.61ms        ? ?/sec    1.00     89.6±1.39ms        ? ?/sec
decode_fixed_binary_hex_json                 1.05     92.9±1.20ms        ? ?/sec    1.00     88.3±1.40ms        ? ?/sec
decode_wide_object_i64_json                  1.38  1468.8±33.63ms        ? ?/sec    1.00  1065.8±27.55ms        ? ?/sec
decode_wide_object_i64_serialize             1.46  1268.0±13.45ms        ? ?/sec    1.00   866.5±14.04ms        ? ?/sec
decode_wide_projection_full_json/131072      1.64       3.0±0.03s    57.4 MB/sec    1.00  1845.3±18.20ms    94.3 MB/sec
decode_wide_projection_narrow_json/131072    1.00   780.7±12.09ms   222.9 MB/sec    1.01   791.4±10.94ms   219.9 MB/sec

alamb

Thanks @Weijun-H -- I think this PR is a nice improvement. I have some suggestions on how to make it faster and improve the comments, but overall very nice 👍

alamb · 2026-01-10T19:43:47Z

arrow-json/src/reader/struct_array.rs

    is_nullable: bool,
    struct_mode: StructMode,
+    field_name_to_index: Option<HashMap<String, usize>>,
+    child_pos: Vec<u32>,


Could you add a comment that explains what child_pos is? It isn't clear here (the idea of caching rather than recreating it looks good though)

Specifically I think it is important to document what is stored at each index (e.g. each index the tape position of at field_idx * row_count + row)

renamed and commented in df9e710

alamb · 2026-01-10T19:48:17Z

arrow-json/src/reader/struct_array.rs

+                    ))
+                })?;
+        }
+        self.child_pos.resize(total_len, 0);


This seems like it would set some elements to zero twice -- I think you can get the same result without the extra setting via

self.child_pos.clear(); self.child_pos.resize(total_len, 0);

Also, I think resize calls reserve internally (it internally calls extend_with which calls reserve), so there is no need to also call child_pos.reserve above

(also the rest of this crate just calls reserve so I think using try_reserve just here seems unecessary)

addressed in. df9e710

alamb · 2026-01-10T19:50:41Z

arrow-json/src/reader/struct_array.rs

+                                    fields.len()
+                                )));
+                            }
+                            child_pos[entry_idx * row_count + row] = cur_idx;


👍 this is a nice way to avoid allocations

arrow-json/src/reader/struct_array.rs

rluvaton · 2026-01-12T11:42:13Z

arrow-json/src/reader/struct_array.rs

+                let start = field_idx * row_count;
+                let end = start + row_count;
+                let pos = &child_pos[start..end];


Is it possible to extract the field_tape_positions into another private struct that expose the api and hide the implementation detail

refactored in. ad44ec2

rluvaton · 2026-01-12T11:43:35Z

arrow-json/src/reader/struct_array.rs

+                                    fields.len()
+                                )));
+                            }
+                            child_pos[entry_idx * row_count + row] = cur_idx;


This can also be part of the dedicated struct

refactored in ad44ec2

…exing in StructArrayDecoder

…ecoders and field index creation

…ecoder for improved clarity and performance

…der for improved clarity and performance

alamb · 2026-01-13T16:22:18Z

run benchmark json-reader

alamb-ghbot · 2026-01-13T16:22:28Z

🤖 ./gh_compare_arrow.sh gh_compare_arrow.sh Running
Linux aal-dev 6.14.0-1018-gcp #19~24.04.1-Ubuntu SMP Wed Sep 24 23:23:09 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux
Comparing optimize-json-scan (ad44ec2) to 4ddaa8c diff
BENCH_NAME=json-reader
BENCH_COMMAND=cargo bench --features=arrow,async,test_common,experimental --bench json-reader
BENCH_FILTER=
BENCH_BRANCH_NAME=optimize-json-scan
Results will be posted here when complete

alamb

😍 -- thank you @Weijun-H @rluvaton and @scovich -- this is looking very nice

alamb-ghbot · 2026-01-13T16:37:20Z

🤖: Benchmark completed

Details

group                                        main                                   optimize-json-scan
-----                                        ----                                   ------------------
decode_binary_hex_json                       1.01     21.0±0.13ms        ? ?/sec    1.00     20.8±0.11ms        ? ?/sec
decode_binary_view_hex_json                  1.00     22.9±0.67ms        ? ?/sec    1.07     24.6±0.60ms        ? ?/sec
decode_fixed_binary_hex_json                 1.00     22.3±0.12ms        ? ?/sec    1.07     23.9±0.28ms        ? ?/sec
decode_wide_object_i64_json                  1.41  1430.5±13.14ms        ? ?/sec    1.00  1011.0±14.53ms        ? ?/sec
decode_wide_object_i64_serialize             1.45   1231.1±6.66ms        ? ?/sec    1.00    848.4±8.01ms        ? ?/sec
decode_wide_projection_full_json/131072      1.64       3.0±0.01s    58.0 MB/sec    1.00  1825.6±15.63ms    95.3 MB/sec
decode_wide_projection_narrow_json/131072    1.00    775.3±5.94ms   224.4 MB/sec    1.04   808.6±13.52ms   215.2 MB/sec

alamb · 2026-01-13T16:56:49Z

run benchmark json-reader

alamb-ghbot · 2026-01-13T16:56:56Z

🤖 ./gh_compare_arrow.sh gh_compare_arrow.sh Running
Linux aal-dev 6.14.0-1018-gcp #19~24.04.1-Ubuntu SMP Wed Sep 24 23:23:09 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux
Comparing optimize-json-scan (ad44ec2) to 4ddaa8c diff
BENCH_NAME=json-reader
BENCH_COMMAND=cargo bench --features=arrow,async,test_common,experimental --bench json-reader
BENCH_FILTER=
BENCH_BRANCH_NAME=optimize-json-scan
Results will be posted here when complete

alamb · 2026-01-13T16:59:42Z

🤔 #9086 (comment) shows some slowdowns. I will rerun and see if I can reproduce

alamb-ghbot · 2026-01-13T17:11:47Z

🤖: Benchmark completed

Details

group                                        main                                   optimize-json-scan
-----                                        ----                                   ------------------
decode_binary_hex_json                       1.01     21.1±0.43ms        ? ?/sec    1.00     20.8±0.29ms        ? ?/sec
decode_binary_view_hex_json                  1.00     22.8±0.71ms        ? ?/sec    1.07     24.3±0.23ms        ? ?/sec
decode_fixed_binary_hex_json                 1.00     22.0±0.48ms        ? ?/sec    1.09     24.0±0.16ms        ? ?/sec
decode_wide_object_i64_json                  1.44  1436.5±12.54ms        ? ?/sec    1.00   996.4±13.49ms        ? ?/sec
decode_wide_object_i64_serialize             1.46   1238.6±6.11ms        ? ?/sec    1.00    847.6±7.72ms        ? ?/sec
decode_wide_projection_full_json/131072      1.69       3.0±0.01s    57.3 MB/sec    1.00  1800.2±12.70ms    96.7 MB/sec
decode_wide_projection_narrow_json/131072    1.00    774.6±5.39ms   224.6 MB/sec    1.01    785.4±5.72ms   221.5 MB/sec

alamb · 2026-01-13T17:47:38Z

🤔 these look like they might be a bit slower now

group                                        main                                   optimize-json-scan
-----                                        ----                                   ------------------
decode_binary_view_hex_json                  1.00     22.8±0.71ms        ? ?/sec    1.07     24.3±0.23ms        ? ?/sec
decode_fixed_binary_hex_json                 1.00     22.0±0.48ms        ? ?/sec    1.09     24.0±0.16ms        ? ?/sec

…p) (apache#9086) # Which issue does this PR close?  - Closes #NNN. # Rationale for this change Optimize JSON struct decoding on wide objects by reducing per-row allocations and repeated field lookups.  # What changes are included in this PR? Reuse a flat child-position buffer in `StructArrayDecoder` and add an optional field-name index for object mode. Skip building the field-name index for list mode; add overflow/allocation checks. ``` decode_wide_object_i64_json time: [11.828 ms 11.865 ms 11.905 ms] change: [−67.828% −67.378% −67.008%] (p = 0.00 < 0.05) Performance has improved. Found 3 outliers among 100 measurements (3.00%) 2 (2.00%) high mild 1 (1.00%) high severe decode_wide_object_i64_serialize time: [7.6923 ms 7.7402 ms 7.7906 ms] change: [−75.652% −75.483% −75.331%] (p = 0.00 < 0.05) Performance has improved. Found 1 outliers among 100 measurements (1.00%) 1 (1.00%) high mild ```  # Are these changes tested? Yes  # Are there any user-facing changes? No

github-actions bot added the arrow Changes to the arrow crate label Jan 2, 2026

Weijun-H marked this pull request as ready for review January 2, 2026 13:57

Weijun-H changed the title ~~perf: improve field indexing in StructArrayDecoder~~ perf: improve field indexing in StructArrayDecoder (1.5x speed up) Jan 2, 2026

Weijun-H changed the title ~~perf: improve field indexing in StructArrayDecoder (1.5x speed up)~~ perf: improve field indexing in StructArrayDecoder (2x speed up) Jan 2, 2026

Weijun-H changed the title ~~perf: improve field indexing in StructArrayDecoder (2x speed up)~~ perf: improve field indexing in StructArrayDecoder (1.7x speed up) Jan 2, 2026

scovich reviewed Jan 5, 2026

View reviewed changes

alamb reviewed Jan 6, 2026

View reviewed changes

alamb changed the title ~~perf: improve field indexing in StructArrayDecoder (1.7x speed up)~~ perf: improve field indexing in JSON StructArrayDecoder (1.7x speed up) Jan 7, 2026

alamb added the performance label Jan 10, 2026

apache deleted a comment from alamb-ghbot Jan 10, 2026

Weijun-H force-pushed the optimize-json-scan branch from 7e3077e to 06ded8b Compare January 10, 2026 12:55

alamb approved these changes Jan 10, 2026

View reviewed changes

alamb mentioned this pull request Jan 11, 2026

Andrew Lamb Weekly-ish Open Source plan - 2026-01-05 apache/datafusion#19652

Closed

44 tasks

rluvaton reviewed Jan 12, 2026

View reviewed changes

arrow-json/src/reader/struct_array.rs Show resolved Hide resolved

rluvaton reviewed Jan 12, 2026

View reviewed changes

Weijun-H added 6 commits January 13, 2026 15:37

feat: add benchmark for JSON reader performance and improve field ind…

1ad724f

…exing in StructArrayDecoder

refactor: streamline StructArrayDecoder initialization by combining d…

f25902d

…ecoders and field index creation

chore

47bd73b

chore

1195aa2

refactor: replace child_pos with field_tape_positions in StructArrayD…

04bea37

…ecoder for improved clarity and performance

refactor: replace Vec<u32> with FieldTapePositions in StructArrayDeco…

ad44ec2

…der for improved clarity and performance

Weijun-H force-pushed the optimize-json-scan branch from 450e491 to ad44ec2 Compare January 13, 2026 13:37

alamb approved these changes Jan 13, 2026

View reviewed changes

alamb merged commit f122d77 into apache:main Jan 13, 2026
23 checks passed

perf: improve field indexing in JSON StructArrayDecoder (1.7x speed up) #9086

perf: improve field indexing in JSON StructArrayDecoder (1.7x speed up) #9086

Uh oh!

Conversation

Weijun-H commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which issue does this PR close?

Rationale for this change

What changes are included in this PR?

Are these changes tested?

Are there any user-facing changes?

Uh oh!

scovich left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alamb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alamb commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alamb-ghbot commented Jan 10, 2026

Uh oh!

Weijun-H commented Jan 10, 2026

Uh oh!

alamb-ghbot commented Jan 10, 2026

Uh oh!

alamb-ghbot commented Jan 10, 2026

Uh oh!

alamb-ghbot commented Jan 10, 2026

Uh oh!

alamb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alamb commented Jan 13, 2026

Uh oh!

alamb-ghbot commented Jan 13, 2026

Uh oh!

alamb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alamb-ghbot commented Jan 13, 2026

Uh oh!

alamb commented Jan 13, 2026

Uh oh!

alamb-ghbot commented Jan 13, 2026

Uh oh!

alamb commented Jan 13, 2026

Weijun-H commented Jan 2, 2026 •

edited

Loading

alamb commented Jan 10, 2026 •

edited

Loading